home *** CD-ROM | disk | FTP | other *** search
/ Languguage OS 2 / Languguage OS II Version 10-94 (Knowledge Media)(1994).ISO / language / pascal / pasos2.man < prev    next >
Text File  |  1994-10-29  |  16KB  |  449 lines
  1.  
  2.     PASCAL compiler, ALPHA 0.2a release for OS/2 en DOS
  3.  
  4.                             Eindhoven, 9 june 1994
  5.  
  6.     COMMAND
  7.         pc    [options] <filename>.<ext>
  8.         pas [options] <filename>.<ext>
  9.  
  10.     DESCRIPTION
  11.  
  12.     This is the temporary manual page for
  13.  
  14.          the pascal compiler frontend,
  15.          the pascal compiler.
  16.  
  17.     In general it should be sufficient to use the compiler in the following
  18.     way:
  19.         'pc file.pas'
  20.         'pc otherfile.s'
  21.         'pc stillotherfile.o'
  22.  
  23.     This creates a file 'file.exe' which can be executed.
  24.  
  25.     The PASCAL 'version' implemented is as close to the standard level(0)
  26.     as possible. There are a few extentions, a few ommisions, plenty of
  27.     bugs, and some not yet implemented areas.
  28.  
  29.     The actual code is transformed in several steps:
  30.         1)    The user code is passed through the preprocessor.
  31.         2)    Then 'pas' is used to transform the resulting PASCAL into
  32.               assembly.
  33.         3)    The assembly code is used to create the objectcode for
  34.               the module.
  35.         4)    Which is linked together with the PASCAL library, p.a,
  36.               and creates a the resulting executable.
  37.  
  38.     To watch these steps, just add the -v switch to the pc command.
  39.  
  40.     OPTIONS for pc
  41.         -v*     Show command the frontend executes.
  42.         -Dname
  43.         -Dname=def Set definitions for the preprocessor.
  44.         -Uname  Instruct the preprocessor to undefine 'name'.
  45.         -S        Generate an assembly file and terminate
  46.         -c        Generate an object file, but do not link.
  47.         -E        Only run the preprocessor on the file, and write results to
  48.             standard ouput.
  49.         -o <file>         Specify the file in which the result should be
  50.             written.
  51.         -h        Runtime help information.
  52.         -Q        Suppress the copyright info when pc starts
  53.         -x        Generate a crossreference in <filename>.xrf
  54.         -G        Generate GAS typical code and use GAS to assemble.
  55.  
  56.     OPTIONS for pas
  57.         -v*     Switch verbosity one level higher.
  58.         -h        Runtime help information.
  59.         -x        Generate a crossreference in <filename>.xrf
  60.         -G        Generate GAS typical code and use GAS to assemble.
  61.  
  62.         -d        Debugging options.
  63.             abEePprsTt
  64.             Most of these switches are used for debugging the compiler
  65.             and of little use to a normal user.
  66.         a     Insert numerous comments into the assembly
  67.         b*    Give information on BackEnd selections
  68.         r     List the tokens found by the scanner
  69.         p     Show which rules are matched in the parser
  70.         i     dump the identifier table to <filename>.ids
  71.         t/T*  dump the AST/defs tree (or more Tree)
  72.                 to <filename>.tre for AST trees
  73.                 to <filename>.syt for defs-trees
  74.         s     write a trace of the semantic evaluation
  75.                 to <filename>.sem
  76.         P     Dump the predefined environment.
  77.         e/E*  List the environments on numerous ocassions
  78.  
  79.          * indicates that a switch has levels, multiple specification
  80.            of the switch indicates "more" of that switch.
  81.            Capitals of those switches increment the debugging level
  82.            with five lowercases.
  83.  
  84.     PREPROCESSING
  85.     The preprocessor knows about PASCAL like comments and should be able
  86.     to handle (*{}*) or {(**)} correctly.
  87.     It also knows the following "pragmas":
  88.         #include
  89.         #define
  90.         #undef
  91.         #if
  92.         #ifdef
  93.         #ifndef
  94.         #else
  95.     A pragma has to be a single line, unless the EOLN is escaped by a '\'
  96.     The '#'-mark has to be in the first position on the line.
  97.  
  98.     ASSEMBLERS
  99.  
  100.     NOTE: IMPORTANT.
  101.     This compiler does not include an assembler, but it does require one.
  102.     This forth release can only use:
  103.     GNU/GAS which can run on the EMX environment for DOS and OS2.
  104.     The current version of EMX used is emx-0.8h, be shure to use this
  105.     version. Otherwise get an upgrade.
  106.     (Note that for execution undr DOS a CO-processor is required.
  107.       The Pascal compiler uses floating point at some places.
  108.       This will be changed in the near future.)
  109.  
  110.     If you have installed the EMX gnu compiler tools, you can use GNU/GAS
  111.     which is the default. If you have installed only the emx-runtime
  112.     environment installed you'll need to add some extra tools.
  113.  
  114.            Install emxrt
  115.                emxdev
  116.                gnudev. (See the install.emx file)
  117.  
  118.     These files are part of the EMX distribution which includes GNU/GCC.
  119.  
  120.     DEBUGGING
  121.  
  122.     Not much attention has (yet) been given to debugging and creating
  123.     debugging information. I debug the programs on assembly language level
  124.     using IBM's IPMD and GNU gdb.
  125.     You don't want to do this, unless you're familiar with the 386-code,
  126.     since no PASCAL code is included. And it can be mind boggling to find
  127.     out what is going on.
  128.  
  129.     EXTENTIONS
  130.     Several extenstions have been implemented to make life a little easier.
  131.  
  132.     Comments:    A comment started by one version of the comments
  133.             starter, has to be terminated by the matching comment
  134.             close combination. They cannot be nested.
  135.             Thus the following are complete comments:
  136.             {(**)}, (*{}*). (*}*) {*)}
  137.             Not correct are:
  138.             {*), (*}, (*{*), {(*} or {(*{}*)}
  139.  
  140.     Identifiers:    Identifiers can contain '_' and '$' as valid characters.
  141.             if '_' of '$' is used first character then the
  142.             second character has to be one from the
  143.             set ['a'..'z','A'..'Z'].
  144.             Identifiers are case insensitive.
  145.  
  146.     Declaration order    The declaration order of constants, types,
  147.             variables and routines is not required. These
  148.             declaration blocks can be repeated multiple times in
  149.             any order. The only restriction is that pointer-type
  150.             definitions are teh only definitions that can refer to
  151.             types yet to be declared.
  152.  
  153.     EXTERNAL    Next to the 'FORWARD' directive for routines, is the
  154.             'EXTERNAL' directive available as an indication to the
  155.             compiler/assembler that code for this routine is to be
  156.             found elsewhere. The syntax equals that of a 'FORWARD'
  157.             definition.
  158.  
  159.     CEXTERNAL    Is used to link against routines available in the
  160.             C-libs. Currently the GNU/EMX convention is supported
  161.             for integers and reals, procedure and functions.
  162.             Again the definitions is equal to 'FORWARD'
  163.             definitions.
  164.             The C-compiler convention that names are prefixed by a
  165.             '_' is supported and thus routines names in PASCAL need
  166.             not start with a '_'.
  167.             Eg:
  168.               C:       extern int atoi(char *);
  169.               PASCAL:  string = array[1..8] of char;
  170.                    FUNCTION atoi( s :string): integer;
  171.                        CEXTERNAL;
  172.  
  173.     CASE-statement    The CASE-statement has been expanded with a default
  174.             clause. Both OTHERWISE and ELSE are recognised as
  175.             default selectors. This is the grammar for the
  176.             extention:
  177.  
  178.       statement9a    =    'CASE' expression 'OF' case_list case_default case_end.
  179.  
  180.       case_default     =  <
  181.     /* A Microsoft extention */
  182.     case_default1  =  'OTHERWISE' statement  .
  183.     case_default1a =  ';' 'OTHERWISE' statement  .
  184.  
  185.     /* A Turbo Pascal extention */
  186.     case_default2  =  'ELSE' statement .
  187.       >.
  188.  
  189.       MinInt        Next to the constant MaxInt (2147483647) is also the
  190.             constant MinInt (-2147483648) available.
  191.  
  192.       Reset, Rewrite
  193.       Assign        To be able to interact with the filesystem, it is
  194.             possible to use the procedure
  195.                 Reset  (Var f: anyfile, s :string),
  196.                 ReWrite(Var f: anyfile, s :string),
  197.                 ASSIGN (Var f: anyfile, s :string),
  198.             an associate an external filename with an internal file.
  199.  
  200.             A reset or rewrite without a filename specifier will
  201.             try to open a file with the name 'f'. If no such name
  202.             exists in Reset an error results. Rewrite creates the
  203.             file and writes to it.
  204.  
  205.     MULTI MODULE COMPILATION
  206.  
  207.     It is now possible to compile MODULEs which contain code fragments,
  208.     and need a PROGRAM module for execution. (One can also check the code
  209.     in the library.)
  210.  
  211.     Syntax:
  212.  
  213.     MODULE = 'module' <decls> 'begin' <code> 'end'.        (1)
  214.            | 'module' <decls> 'end'.                       (2)
  215.            ;
  216.  
  217.     The <code> part in (1) is intended for initialising the preconditions
  218.     for the module.
  219.  
  220.     NB: These codeparts are currently ignored! So one will have to call an
  221.     initialiser routine manually. (This will probably change in a next
  222.     release)
  223.  
  224.     There is currently no supported way to use variables which are declared
  225.     in other modules, other than redeclaring them in every module and have
  226.     the linker resolve the linkages.
  227.  
  228.     NOTE:
  229.     This also means that one cannot use the same identifier at the global
  230.     level in multiple places, without the "feature" that they share the
  231.     same location. (Global variables like 'i' are going to suffer most.)
  232.  
  233.     For procedures and routines is the attribute 'EXTERNAL' available.
  234.         Eg.: 'Procedure SomeWhereElse(i;integer); EXTERNAL'
  235.  
  236.     OMMISIONS
  237.  
  238.     PACKED        The keyword 'PACKED' is allowed in declarations but is
  239.             ignored. Using it does not give any allocation
  240.             advantages. The accompanying routines 'PACK' and
  241.             'UNPACK' are not implemented. They are recognised by
  242.             the scanner/parser.
  243.  
  244.     CONFORMANT ARRAY    Conformant arrays are not included with a PASCAL
  245.             level(0) implementation.
  246.  
  247.     FEATURES
  248.  
  249.     SET        A set can be as big as 64K elements, and the
  250.             limits are -32768..32767.
  251.  
  252.     NOT YET IMPLEMENTED
  253.  
  254.     ROUTINES as parameters.
  255.             The PASCAL standard allows routines to passed a
  256.             parameters to other routines. The parser will recognise
  257.             the code but during semantic analysis the
  258.             constructions will be refused.
  259.  
  260.     KNOWN BUGS
  261.  
  262.     Dependant on your compiler history you will find that certain
  263.     compile-time checks are not enforced.
  264.     Other than some relaxed requirements and extentions, are there really
  265.     some bugs that should be brought to the attention of the
  266.     compiler-writer since they create too much freedom for erronous
  267.     programs.
  268.     Please report these ommisions.
  269.  
  270.     The LIBRARY_PATH environment variable (also used by GCC) should not
  271.     contain more than one directory. This restriction will disapear in
  272.     near future.
  273.  
  274.     When using reset/rewrite with one character names (eg. 'f'), the name
  275.     needs to be manually assigned and bigger than 1 character. Otherwise
  276.     compile-time errors will occur.
  277.     Eg.:
  278.         assign(f, 'ff');
  279.         rewrite(f);
  280.  
  281.     BUGS
  282.  
  283.     There should be a lot less bugs this time, they will be still around
  284.     though. That is why this version is still an ALPHA release.
  285.     There are several flaws in the code generation. And although many case
  286.     have been tested in isolation, complex situations can cause wrong code
  287.     to be generated.
  288.     Please report these to the author, so that they can be fixed.
  289.     (Or at least mentioned in the buglist)
  290.  
  291.     The compiler is sometimes able to recognise the fact that it is in an
  292.     inconsistent state.
  293.     Then usually informational text is written to the screen.
  294.     This output, your input, and possibly the core dump, can be of help to
  295.     me. you can (E)mail me all parts involved. (Prefably stripped to the
  296.     smallest code-chunk which still exhibits the behaviour.)
  297.  
  298.  
  299.     These messages can look like:
  300.  
  301.          "Houston, Code generation problem.
  302.           Program aborted."
  303.         Or:
  304.  
  305.          "Houston, we've got a serious problem with the register
  306.               allocation.
  307.           Program aborted."
  308.  
  309.         Or a large sequence of what looks like semi machine instructions.
  310.  
  311.     Which means that yor programmed a program sequence which confuses the
  312.     codegenerator part of the compiler. This should not happen, so it is
  313.     a compiler bug. Please report this bug.
  314.     Sometimes it is possible to rewrite the expression or statement
  315.     causing the trouble. But you'll have to locate the cullpit.
  316.     The major reason for this is/was that I overlooked a stdroutine/type
  317.     combination.
  318.  
  319.     On several places in the runtime library are tests on the outcome of
  320.     systemcalls. If they fail, a message with that regard is printed on
  321.     'stderr'. Note that this need not always be a error in the library.
  322.     It could also be due to incorrect use of the runtime library by the
  323.     program.
  324.  
  325.     During execution, traps can occur. Usually this means that either
  326.     pointers or array accesses have been outside the current allowed space.
  327.     Eg:
  328.         core dumped
  329.         SYS1808:
  330.         The process has stopped.  The software diagnostic
  331.         code (exception code) is  0005.
  332.  
  333.     These could be compiler errors, but lately I haven't found many of
  334.     those that showed in this blunt way. Usually the compiler shows the
  335.     errors more 'secretly'.
  336.  
  337.     DEFAULTS
  338.  
  339.     Default heap size is set to 1 Mb, but can be changed by recompiling
  340.     the 'heaplib.p' code which is part of the runtime environment.
  341.  
  342.     ENVIRONMENT
  343.  
  344.     PASCAL for OS/2 was generated using Cocktail compiler tools,
  345.     and compiled using the EMX/GCC. The code generated by the PASCAL
  346.     compiler also works with the EMX system. So the runtime environment for
  347.     the compiler has to include the EMX runtime environment.
  348.     In 'install.emx' is documentation available on how to install the
  349.     EMX-run time system. A reduced release of required tools is available
  350.     in 'emxpc.zip'
  351.     For the installation of pasos2 check the readme.pc file.
  352.  
  353.     The PASCAL compiler itself uses several environment variables:
  354.     TMP            The location for intermediate files.
  355.                 Note that this directory has to exist.
  356.     PASLOAD         Specify the number of minutes the compiler
  357.                 image shoul remain resident. This will speedup
  358.                 future compiles.
  359.     PAS_INC         This path will be included in the seachpath for
  360.                 the preprocessor.
  361.     PASPP            The preprocessor to use. Unless you want to
  362.                 use another set it to paspp.
  363.  
  364.     But the linker can use others as well:
  365.     LIB            The path used by LINK386 for libraries.
  366.     PAS_LIB         The path where additional libraries can be
  367.                 found for the linker. (currently ignored)
  368.     LIBRARY_PATH        GNU/GAS libraries need to go into the
  369.                 directory given by this env-variable.
  370.                 Note that the current implementation only
  371.                 allows one directory to be specified in this
  372.                 path.
  373.  
  374.     RUNTIME LIBRARY
  375.  
  376.     The source for the runtime library is included in the package. It is
  377.     the part which is least severly tested. It has several problem areas in
  378.     it, but for most programming it should work.
  379.     One is always free to go through the runtime library code and modify it
  380.     to fit ones own requirements. If these changes are usefull to others as
  381.     well I'd be more than willing to include them in a new release.
  382.  
  383.     The area with most problems in INPUT from an interactive file (eg.:
  384.     input), since different pascal compilers have different kind of
  385.     behaviour. TurboPascal nowhere nearly complies with the standard, and
  386.     as such is it currently hard to mimic it's behaviour.
  387.     [ Unless ofcourse, you are of the opinion that TurboPascal is the
  388.       standard :-( ]
  389.  
  390.     FILES
  391.  
  392.     .pas .p          pascal source files
  393.     .inc .hp .hs         assembler or pascal include files
  394.     .i             pascal preprocessed files
  395.     .asm .s .S         assembler sources
  396.     .obj             MASM/ML object files (not supported)
  397.     .o             GNU/GAS object files
  398.     .lib .a          Library files
  399.     /tmp/pc????         Temporary files
  400.  
  401.     ORIGINAL SOURCE
  402.  
  403.     The most current release of this compiler should always be available
  404.     from:
  405.           ftp.eb.ele.tue.nl:/pub/src/pascal/pasos2?.zip
  406.     or:
  407.           ftp.cdrom.com:/os2/2_x/program/pasos2?.zip
  408.  
  409.     where '?' represents the most recent version.
  410.     Sources of PC and components other than the GNU stuff are not (yet)
  411.     available.
  412.  
  413.     EMX
  414.     EMX is available from:
  415.           ftp.eb.ele.tue.nl:/pub/pc/emx-0.8?
  416.     And a lot of sites much more near you.
  417.           ftp.cdrom.com:/os2/2_x/unix/emx08?
  418.  
  419.     SEE ALSO
  420.  
  421.     Kathleen Jensen and Niklaus Wirth.
  422.     Pascal User and Reference Manual
  423.     Springer Verlag, second edition, 1974.
  424.  
  425.     British Standards Institution.
  426.     Specification fo computer programming language PASCAL, 1984.
  427.     ISO 7185 / BS 6192.
  428.  
  429.     Willem Jan Withagen
  430.     A flexible frontend for a PASCAL compiler
  431.     Technical report Eindhoven University of technology
  432.     ftp: ftp.eb.ele.tue.nl:/pub/src/pascal/frontend.*
  433.  
  434.     AUTHOR
  435.  
  436.     Willem Jan Withagen.              phone: +31-(0)40-473401
  437.     Eindhoven University of Technology      fax:     +31-(0)40-466033
  438.     Room 10.35                  Email: wjw@eb.ele.tue.nl
  439.     PO Box 513
  440.     5600 MB Eindhoven
  441.     The Netherlands
  442.  
  443.     Willem Jan Withagen.              phone:  +31-(0)40-511979
  444.     Martin Luther Kingstraat 48          fax:      +31-(0)40-526825
  445.     5653 MG Eindhoven              Email: wjw@wjw.iaehv.nl
  446.     The Netherlands
  447.  
  448.  
  449.